Face Enrol and Block API

API Description

Objective

Input	Output
The selfie of the customer and an optional block flag.	A response that reflects the success or failure of the customer enrolment process, or the addition to your block-list. The reason for rejecting the enrolment application is also returned if the enrolment fails.

API URL

https://ind-orion.hyperverge.co/v2/enrol/face 

API Endpoint

enrol/face

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Valid Values
Content-type	Mandatory	This parameter defines the media type for the request payload.	multipart/form-data
appId	Mandatory	Application ID shared by HyperVerge	Not Applicable - this is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	Not Applicable - this is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Input

The following table provides the complete information on the parameters used in the request body for the API call.

Parameter	Mandatory or Optional	Type	Allowed Values	Default Value	Description
transactionId	Mandatory	string	This should be both unique and easily associated with the specific user's interaction in your application(s).	Not Applicable	This should be both unique and easily associated with the specific user's interaction in your application(s).
selfie	Mandatory	file	Not Applicable	Not Applicable	The selfie image of the user. Note The maximum image size supported is 6 MB.
block	Optional	string	yes or no	no	If set to "yes", the application is added to the blocklist in the database. During a search operation, it shows up as a part of the blocklist section.

Sample Request

The following code shows a standard curl request for the API.

curl --request POST \
 --url https://ind-orion.hyperverge.co/v2/enrol/face \
 --header 'appId: <Enter_the_appId>' \
 --header 'appKey: <Enter_the_appKey>' \
 --header 'Content-Type: application/json' \
 --header 'accept: application/json' \
 --data '{
    "transactionId": "<Enter_the_Transaction_ID>",
    "selfie": "<Enter_the_path_to_the_Selfie>",
    "block": "no"
  }'

Success Response Sample

{
  "statusCode": 200,
  "metaData": {
    "requestId": "1679333179607-1ea3d8a1-5c62-4e3e-807f-6ad5796c9c96",
    "transactionId": "HV-Orion-Test"
  },
  "result": {
    "data": {
      "transactionId": "HV-Orion-Test",
      "isEnrolled": {
        "value": "yes",
        "reason": "NA"
      },
      "dashboardUrl": "https://www.orion-console.hyperverge.co/reviewportal/1679333179607-1ea3d8a1-5c62-4e3e-807f-6ad5796c9c96"
    },
    "summary": {
      "value": "Enrol successful",
      "action": "Pass"
    }
  }
}

Success Response Details

Object	Field	Description
isEnrolled	value	If the value is yes, the application was successfully enrolled in your database. If the value is no, the reason field provides the reason for the failure in enrollment.
isEnrolled	reason	If the isEnrolled value is no, the reason field describes the cause for the failure in the enrollment process.
summary	action	It displays the recommended decision for the customer. It can take any of the values from the following table. Action Our Recommendation Pass You can proceed with the application as nothing suspicious was found. Manual Review Requires manual review for further approval or rejection. Fail The enrolment failed either because of an image quality issue or a matching transactionId pre-existing in the database.
metaData	requestId	A unique identifier to track the customer's application.
metaData	transactionId	The same transactionId used in the API request.

Error Response Sample

The following are the sample error responses for the API.

Pre-existing Transaction ID

{
"statusCode":200,
"metaData":
  {
  "requestId":"1738059396090-7e92042b-3628-4a05-b076-dbb526d39f68",
  "transactionId":"<Transaction_ID>"
  },
  "result":
  {
    "data":
   {
     "transactionId":"<Transaction_ID>",
     "isEnrolled":
        {
           "value":"no",
           "reason":"Enrolment TransactionId already exists"
         },
         "dashboardUrl":"<Dashboard_URL>"
     },
    "summary":
     {
     "value":"Enrol failed with message: 'TransactionId already exists'",
      "action":"Fail"
     }
  },
     "error":"TransactionId already exists",
     "errorCode":"E_004"
}

Missing Transaction ID

The following is a sample response for a request missing the transactionId.

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "statusCode": 400,
  "error": "\"transactionId\" is required"
}

Missing/Invalid Credentials

{
  "status": "failure",
  "metaData": {
     "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "statusCode": 401,
  "error": "Missing/Invalid credentials"
}

Failed Face Detection in Selfie

{
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "statusCode": 400,
  "error": "Face not detected in Selfie image"
}

Exceeded

{
  "status": "failure",
  "message": "Requests rate limit exceeded",
  "statusCode": 429
}

Internal Server Error

{
  	"status": "failure",
  	"statusCode": "500",
  	"error": {
    	"message": "Internal server error",
    	"timestamp": 1662720725493
  	}
}

Failure and Error Response Details

A failure or error response from the module contains a failure status with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	""transactionId" is required	The request does not contain the transaction identification number.
400	Face not detected in Selfie image	The model failed to detect a face in the selfie. Kindly retry with a new selfie.
401	Missing/Invalid credentials	The request either does not contain the mandatory credentials or contains invalid credentials.
429	Requests rate limit exceeded	The number of transactions per minute has crossed the limit set for your credentials.
500	Internal Server Error	There is an error with HyperVerge's server. Kindly contact the HyperVerge team for resolution.